Premier 1995

Calling Help from your Forms 4.5 application

By Daniel Bill

One of the features you expect in a true Windows application is standard Windows Help functionality--Help that looks and feels the same no matter what application you're in. With the new Developer/2000 tools, you can create applications that add the professional touch of Windows Help and provide users with the Help functionality they're familiar with.

In this article, we'll explore the code you need to access Help from a Forms application. In the next issue, we'll take the process one step further and look at a useful strategy for calling context-sensitive Help from any location in your form.

Creating context-sensitive Help

When you incorporate Help into an application, you'll want it to be context sensitive, meaning that Help should display information that's relevant to your location in the application. You identify locations of topics in Help files using unique numbers called context IDs.

You can display Help information in a Help window or in pop-up boxes. Usually short definitions are displayed in pop-ups, and everything else appears in the Help window.

Creating Help files is a two-step process; first you write the source file and then you compile it. There are several Help authoring tools available. Some are completely standalone; others are built on a word processor. These products create the source Help files (RTF and HPJ) that you then compile to create an HLP file. Compiling is a straightforward process, but it does require the Help compiler, which is available free from Microsoft. (You can download it from the Microsoft forum on CompuServe.) In this article, we'll focus on integrating existing Help files with
your application.

The WinHelp function

Standard Windows functions are available to developers through a file called USER.EXE. Windows developers use the WinHelp function, found in USER.EXE, to access Windows Help. The WinHelp function starts the WINHELP.EXE program. We use a call to WinHelp from a Forms application to start Help. We'll review the WinHelp function here, and then later we'll see how to call it from a form.

The WinHelp function has the interface shown below:

WinHelp(WindowHandle, HelpFileName, HelpCommand, ExtraData)

The arguments that WinHelp uses are described in Figure A.

FIGURE A

Argument/Purpose

WindowHandle An integer number representing the handle of the window that is calling Help.

HelpFileName The name of the Help file to be loaded. If the Help file is in the Windows directory, you supply the filename; if it's in another directory, you must specify the path and filename.

HelpCommand An integer number that represents a particular Help command. The most useful options are listed below:

1 Goes to a particular topic identified by the context number stored in the ExtraData field

3 Displays the Contents screen of the Help file

4 Displays the How-to-use-Help screen

8 Same as option 1, except it displays Help as a pop-up window

257 Displays the search dialog for the Help file

ExtraData Some of the Help commands from the third argument require further data to execute; for example, 1 and 8 require a context number in this field (this is how we get context-sensitive Help), while 3 and 4 do not use this parameter.

Accessing Help from a form

With the Developer/2000 products we now have the ability, using a PL/SQL interface, to access foreign functions stored in dynamic libraries through a built-in package called the ORA_FFI package. This capability allows us to use the WinHelp function stored in the USER.EXE library. Writing a PL/SQL procedure that uses the ORA_FFI package to access foreign functions could be a daunting task, but fortunately there's a simple way to create your procedure.

The simple way

Note: If you don't have access to the Forms demo, you can skip this process and directly enter the code shown in Figure D.

The Developer/2000 forms demo package contains a form that acts as a code generator for creating PL/SQL procedures that access foreign functions. Let's step through it. First, start your Forms demo by clicking on the Forms demo icon in the Developer/2000 Demos group (you must have the demo tables loaded first). Select the Forms++ tab, as shown in Figure B, and then select the Foreign Function Assistant option. This step will take you into the Foreign Function Interface Generator (FFIGEN) form. Here you can enter all the information about the foreign function you want to access. The form will then generate the required procedure as an uncompiled library (PLD) file.

Let's look at how to use this utility to define our Help procedure. Click in the next empty record below the Package Name field and type myhelp (the name we'll call our PL/SQL Help package). In the File Name field, enter user.exe, the name of the dynamic library containing the foreign function. Provide a description, such as Package to call Microsoft Help. Under the Functions heading, enter winhelp, the name of the function in the dynamic library. Continue entering all the parameters until your screen looks like the one shown in Figure C. Be sure to enter the data type for each of the arguments of the WinHelp function. When you've entered all the data, select the save icon to save your information, and then select the lightning bolt icon to execute the generating facility. You should now have a file called MYHELP.PLD.

The contents of MYHELP.PLD are shown in Figure D. We won't explain what each line does. Among other things, this code defines the WinHelp function, declares variables, finds and loads the library, and registers the functions and parameters. (For more information on accessing foreign functions through PL/SQL, see the Forms Advanced Techniques manual.)

FIGURE D

PACKAGE myhelp IS

FUNCTION winhelp

(WinHandle IN PLS_INTEGER,

HelpFileName IN VARCHAR2,

HelpCommand IN PLS_INTEGER,

ExtraData IN PLS_INTEGER)

RETURN PLS_INTEGER;

END myhelp;

PACKAGE BODY myhelp IS

lh_user ora_ffi.libHandleType;

fh_winhelp ora_ffi.funcHandleType;

FUNCTION i_winhelp(funcHandle IN ora_ffi.funcHandleType,WinHandle IN PLS_INTEGER,

HelpFileName IN OUT VARCHAR2,

HelpCommand IN PLS_INTEGER,

ExtraData IN PLS_INTEGER)

RETURN PLS_INTEGER;

PRAGMA INTERFACE(C,i_winhelp,11265);

FUNCTION winhelp (WinHandle IN PLS_INTEGER,

HelpFileName IN VARCHAR2,

HelpCommand IN PLS_INTEGER,

ExtraData IN PLS_INTEGER)

RETURN PLS_INTEGER IS

WinHandle_l PLS_INTEGER := WinHandle;

HelpFileName_l VARCHAR2(512) := HelpFileName;

HelpCommand_l PLS_INTEGER := HelpCommand;

ExtraData_l PLS_INTEGER := ExtraData;

rc PLS_INTEGER;

BEGIN

rc := i_winhelp(fh_winhelp,WinHandle_l,HelpFileName_l,

HelpCommand_l,ExtraData_l);

RETURN (rc);

END ;

BEGIN

BEGIN

lh_user := ora_ffi.find_library('user.exe');

EXCEPTION WHEN ora_ffi.FFI_ERROR THEN

lh_user := ora_ffi.load_library(NULL,'user.exe');

END ;

fh_winhelp :=

ora_ffi.register_function(lh_user,'winhelp',ora_ffi.PASCAL_STD);

ora_ffi.register_parameter(fh_winhelp,ORA_FFI.C_INT);

ora_ffi.register_parameter(fh_winhelp,ORA_FFI.C_CHAR_PTR);

ora_ffi.register_parameter(fh_winhelp,ORA_FFI.C_INT);

ora_ffi.register_parameter(fh_winhelp,ORA_FFI.C_LONG);

ora_ffi.register_return(fh_winhelp,ORA_FFI.C_INT);

END myhelp;

Converting MYHELP.PLD to MYHELP.PLL

The PLD file is a "text format file" version of a library module. In order to attach the MYHELP library to a form, you must first convert it to a PLL format (a compiled version of a library). From Forms Designer, select the File menu, then the Administration option, and then the Convert option. Your screen will now display the Convert dialog box. Fill in all the options as shown in Figure E, and then select the Convert button. You now have a MYHELP.PLL file in the same directory as your MYHELP.PLD file. With your Help procedure created and stored in a library, you can now use it in any of your applications.

Putting it all together

To call Help from a form, first attach the MYHELP.PLL library to your form. Select the Attached Libraries node in the Object Navigator and then select the create icon () (or you can double-click the Attached Libraries node). With the Attach Library dialog box displayed, enter the name, myhelp.pll, and click on the Attach button, as shown in Figure F. The MYHELP.PLL library is now attached to your form.

Let's create a Help button on a form with the PL/SQL code. After you've created a button on your form, label it Help. Then, create a trigger on the Help button by clicking the + beside the Help button node, then clicking on the Triggers node and selecting the create icon. When prompted for the trigger name, select When-Button-Pressed and then click on the OK button. You are now in the PL/SQL editor, as shown in Figure G, ready to enter the code shown in Figure H that will execute the WinHelp function.

FIGURE H

declare

winhandle pls_integer;

HelpCommand pls_integer;

ExtraData pls_integer;

result integer;

begin

winhandle := get_window_property(FORMS_MDI_WINDOW,WINDOW_HANDLE);

HelpCommand := 1;

ExtraData := 1004;

result:= myhelp.winhelp(winhandle, 'yourhelp.hlp', HelpCommand, ExtraData);

end;

A walk through the code...

The first section of code declares the variables. In the Begin section, the first line calls the get_window_property procedure to get the window handle of your form's MDI window. FORMS_MDI_WINDOW is a system variable containing the ID of the MDIparent window for your form. The HelpCommand variable can contain any of the valid values we discussed earlier. You use the ExtraData variable to store the context ID of the Help topic you want to go to. The last line calls the WinHelp function stored in the MyHelp library, passing it the window handle, the Help filename, the Help command you want to execute, and any extra data depending on which Help command you selected. In this example, we're setting HelpCommand to 1, which tells the WinHelp function we want to display a specific Help topic as specified by the context ID stored in the ExtraData field, in this case 1004. The result variable is used to store the return value of the WinHelp function, 1 if the call was successful and 0 if it failed.

Finally, select the Compile All option under the File menu. Save the form and run it.

Congratulations! You've created a form with full Windows Help functionality! Go ahead and try it. In the next issue, we'll discuss strategy and some helpful hints for integrating Help into an application.

Daniel Bill is a project leader working for the City of Mississauga in Ontario, Canada. He is also one of Oracle's "Developer/2000 Ambassadors." You can reach him via e-mail at daniel.bill@city.mississauga.on.ca.

[Return to Index for Exploring Oracle Developer/2000 and Designer/2000 - Premier 1995]

Copyright (c) 1995 The Cobb Group, a division of Ziff-Davis Publishing Company. All rights reserved.

Reproduction in whole or in part in any form or medium without express written permission of Ziff-Davis

Publishing Company is prohibited. The Cobb Group and The Cobb Group logo are trademarks of

Ziff-Davis Publishing Company.

Exploring Oracle Developer/2000 and Designer/2000 is a publication of The Cobb Group.

1-800-223-8720